home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2005 October / PCWOCT05.iso / Software / FromTheMag / XAMPP 1.4.14 / xampp-win32-1.4.14-installer.exe / xampp / php / pear / docs / mailparse / .tmpREADME < prev    next >
Text File  |  2004-03-24  |  6KB  |  166 lines
  1. mailparse library for PHP 4
  2. ===========================
  3. $Id: README,v 1.3 2002/09/10 11:20:45 wez Exp $
  4.  
  5. Mailparse is an extension for parsing and working with email messages.
  6. It can deal with rfc822 and rfc2045 (MIME) compliant messages.
  7. Mailparse is stream based, which means that it does not keep in-memory
  8. copies of the files it processes - so it is very resource efficient
  9. when dealing with large messages.
  10.  
  11. OO Syntax:
  12. =============
  13. <?php
  14. $file = "/path/to/rfc822/compliant/message";
  15. // parse the message in $file.
  16. // The file MUST remain in existence until you are finished using
  17. // the object, as mailparse does not cache the file in memory.
  18. // You can also use two alternative syntaxes:
  19. // 
  20. // Read the message from a variable:
  21. //   $msg =& new MimeMessage("var", $message);
  22. //
  23. // Read the message from a stream (from fopen).
  24. // The stream MUST be seekable, or things will not work correctly.
  25. // Also, you MUST NOT fclose the stream until you have finished
  26. // using the message object (or any child objects it returns).
  27. //   $msg =& new MimeMessage("stream", $fp);
  28. //
  29. $msg =& new MimeMessage("file", $file);
  30.  
  31. // Process the message.
  32. display_part_info("message", $msg);
  33.  
  34. // Little function to display things
  35. function display_part_info($caption, &$msgpart)
  36. {
  37.     echo "Message part: $caption\n";
  38.     
  39.     // The data member corresponds to the information
  40.     // available from the mailparse_msg_get_part_data function.
  41.     // You can access a particular header like this:
  42.     //   $subject = $msgpart->data["headers"]["subject"];
  43.     var_dump($msgpart->data);
  44.  
  45.     echo "The headers are:\n";
  46.     // Display the headers (in raw format) to the browser output.
  47.     // You can also use:
  48.     //   $msgpart->extract_headers(MAILPARSE_EXTRACT_STREAM, $fp);
  49.     //     to write the headers to the supplied stream at it's current
  50.     //     position.
  51.     //
  52.     //   $var = $msgpart->extract_headers(MAILPARSE_EXTRACT_RETURN);
  53.     //     to return the headers in a variable.
  54.     $msgpart->extract_headers(MAILPARSE_EXTRACT_OUTPUT);
  55.  
  56.     // Display the body if this part is intended to be displayed:
  57.     $n = $msgpart->get_child_count();
  58.  
  59.     if ($n == 0) {
  60.         // Return the body as a string (the MAILPARSE_EXTRACT parameter
  61.         // acts just as it does in extract_headers method.
  62.         $body = $msgpart->extract_body(MAILPARSE_EXTRACT_RETURN);
  63.         echo htmlentities($body);
  64.         
  65.         // This function tells you about any uuencoded attachments
  66.         // that are present in this part.
  67.         $uue = $msgpart->enum_uue();
  68.         if ($uue !== false) {
  69.             var_dump($uue);
  70.             foreach($uue as $index => $data) {
  71.                 // $data => array("filename" => "original filename",
  72.                 //                "filesize" => "size of extracted file",
  73.                 //               );
  74.  
  75.                 printf("UUE[%d] %s (%d bytes)\n",
  76.                     $index, $data["filename"],
  77.                     $data["filesize"]);
  78.  
  79.                 // Display the extracted part to the output.
  80.                 $msgpart->extract_uue($index, MAILPARSE_EXTRACT_OUTPUT);
  81.  
  82.             }
  83.         }
  84.  
  85.     } else {
  86.         // Recurse and show children of that part
  87.         for ($i = 0; $i < $n; $i++) {
  88.             $part =& $msgpart->get_child($i);
  89.             display_part_info("$caption child $i", $part);
  90.         }
  91.     }
  92. }
  93.  
  94. ?>
  95.  
  96. ////////////// The rest of this document may be out of date!
  97. // Take a look at the mailparse section of the online manual
  98. // for more hints about this stuff.
  99.  
  100. $mime = mailparse_rfc2045_parse_file($file);
  101. $ostruct = mailparse_rfc2045_getstructure($mime);
  102. foreach($ostruct as $st)    {
  103.     $section = mailparse_rfc2045_find($mime, $st); 
  104.     $struct[$st] = mailparse_rfc2045_getinfo($section);
  105. }
  106. var_dump($struct);
  107. ?>
  108. array mailparse_rfc822_parse_addresses(string addresses)
  109.     parses an rfc822 compliant recipient list, such as that found in To: From:
  110.     headers.  Returns a indexed array of assoc. arrays for each recipient:
  111.     array(0 => array("display" => "Wez Furlong", "address" => "wez@php.net"))
  112.  
  113. resource mailparse_rfc2045_create()
  114.     Create a mime mail resource
  115.  
  116. boolean mailparse_rfc2045_parse(resource mimemail, string data)
  117.     incrementally parse data into the supplied mime mail resource.
  118.     Concept: you can stream portions of a file at a time, rather than read
  119.     and parse the whole thing.
  120.  
  121.  
  122. resource mailparse_rfc2045_parse_file(string $filename)
  123.     Parse a file and return a $mime resource.
  124.     The file is opened and streamed through the parser.
  125.     This is the optimal way of parsing a mail file that
  126.     you have on disk.
  127.  
  128.         
  129. array mailparse_rfc2045_getstructure(resource mimemail)
  130.     returns an array containing a list of message parts in the form:
  131.     array("1", "1.1", "1.2")
  132.  
  133. resource mailparse_rfc2045_find(resource mimemail, string partname)
  134.     returns an mime mail resource representing the named section
  135.     
  136. array mailparse_rfc2045_getinfo(resource mimemail)
  137.     returns an array containing the bounds, content type and headers of the
  138.       section.
  139.  
  140. mailparse_rfc2045_extract_file(resource mimemail, string filename[, string
  141.         callbackfunc])
  142.     Extracts/decodes a message section from the supplied filename.
  143.     If no callback func is supplied, it outputs the results into the current
  144.     output buffer, otherwise it calls the callback with a string parameter
  145.     containing the text.    
  146.     The contents of the section will be decoded according to their transfer
  147.     encoding - base64, quoted-printable and uuencoded text are supported.
  148.  
  149. All operations are done incrementally; streaming the input and output so that
  150. memory usage is on the whole lower than something like procmail or doing this
  151. stuff in PHP space.  The aim is that it stays this way to handle large
  152. quantities of email.
  153.  
  154. TODO:
  155. =====
  156.  
  157. . Add support for binhex encoding?
  158. . Extracting a message part without decoding the transfer encoding so that
  159.     eg: pgp-signatures can be verified.
  160.  
  161. . Work the other way around - build up a rfc2045 compliant message file from
  162.     simple structure information and filenames/variables.
  163.     
  164. vim:tw=78
  165. vim600:syn=php:tw=78
  166.